<?php
	$title = "FAQ";
	include("header.html");
?>

<h1>Frequently Asked Questions</h1>


<h2>General</h2>


<div class="faq">
    <div class="question">
        <p>
            Where does the name "Cobertura" come from?
        </p>
    </div>

    <div class="answer">
        <p>
            "Cobertura" is the Spanish and Portuguese word for "coverage." We
            were trying to avoid acronyms and coffee references. It's not too
            hard to associate the word "cobertura" with the word "coverage,"
            and it even has a bit of a zesty kick to it!
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Who started this project?
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura is based on jcoverage, which was created by
            jcoverage ltd. Cobertura was started by Mark Doliner
            when he was an employee of
            <a href="http://www.sas.com/">SAS</a>. SAS paid Mark
            to create the initial version of the project and get
            it off the ground.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Who works on this project?
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura is currently developed by
        </p>

        <ul>
            <li>Joakim Erdfelt</li>
            <li>John Lewis</li>
            <li>Grzegorz Lukasik</li>
            <li>Jiří Mareš</li>
            <li>Jeremy Thomerson</li>
        </ul>

        <p>
            With help from other supporters of open source
            development. See the
            <a href="http://cobertura.svn.sourceforge.net/viewvc/*checkout*/cobertura/trunk/cobertura/COPYRIGHT">COPYRIGHT
                file distributed with Cobertura</a> for the
            full list of contributors.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Can I help?
        </p>
    </div>

    <div class="answer">
        <p>
            Yes! Just <a href="download.html">check out the most recent code
            from our Subversion repository</a> and start hacking. Please try to
            follow the same naming, coding and formatting conventions as the rest
            of Cobertura. Patches can be submitted to our
            <a href="https://sourceforge.net/tracker/?group_id=130558&amp;atid=720017">patch
                tracker</a>.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Who should I contact with questions?
        </p>
    </div>

    <div class="answer">
        <p>
            Please use the
            <a href="http://lists.sourceforge.net/lists/listinfo/cobertura-devel">cobertura-devel</a>
            mailing list for all questions. This way the entire community can
            benefit from the answers.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Why should I use Cobertura instead of one of the other code coverage
            tools?
        </p>
    </div>

    <div class="answer">
        <p>
            We think Cobertura produces the prettiest output. Pretty output means
            it's easy to read. Easy to read means you waste less time figuring
            out where to add test coverage. We also think Cobertura is easy to
            get running.
        </p>
    </div>
</div>


<br/>


<div class="faq">
<div class="question">
    <p>
        Why did you feel a need to fork jcoverage?
    </p>
</div>

<div class="answer">
    <p>
        We felt it would be beneficial for the Java community if there were a
        Java coverage tool with a more open development process than jcoverage
        and Clover.
    </p>

    <p>
        The GPL release of jcoverage had not been updated in about a year and
        a half. This in and of itself is ok, but the last release of
        jcoverage (1.0.5) has a bug which causes jcoverage to fail in Windows
        when used on a large number of classes (generally about two or three
        hundred). The bug is caused by the jcoverage ant tasks using a
        command line that is too large for Windows. A jcoverage user
        submitted a patch to the jcoverage bug tracker to fix the problem,
        but it was never officially released as a part of jcoverage/gpl.
    </p>

    <p>
        Also, the version of BCEL distributed with jcoverage 1.0.5 causes
        problems when used with Java classes compiled with a 1.5 JDK.
    </p>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            What about <a href="http://emma.sourceforge.net/">Emma</a>?
        </p>
    </div>

    <div class="answer">
        <p>
            We haven't used it very much, but it looks like it does a pretty good
            job. Judging from the sample on the Emma web page, we think
            the Cobertura HTML reports are a bit easier to digest. It looks like
            Emma has some nice usability features, such as the ability to
            instrument all classes in a jar file with one command. A little
            friendly competition never hurt anyone.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            What do I need to use Cobertura?
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura should work on any platform with with Java 5 or newer. The Cobertura download packages include all
            the dependencies you'll need (ASM, log4j, etc.)
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            What is code complexity and why should I care about it?
        </p>
    </div>

    <div class="answer">
        <p>
            McCabe's cyclomatic code complexity algorithm is used to determine
            how "complex" a given piece of code is. As code becomes more
            complex, it becomes more error prone. If a class has a high
            complexity number, then that class is a good target for additional
            test coverage.
        </p>
    </div>
</div>


<h2>Usage</h2>


<div class="faq">
    <div class="question">
        <p>
            When I generate coverage reports, why do they always show
            100% coverage everywhere?
        </p>

        <p>
            When I generate coverage reports, why do they always show
            0% coverage everywhere?
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura is probably using
            the wrong .ser file when generating the reports. When you instrument
            your classes, Cobertura generates a .ser file containing basic
            information about each class. As your tests run, Cobertura
            adds additional information to this same data file. If the instrumented
            classes can not find the data file when running then they
            will create a new one. It is important that you use the same
            cobertura.ser file when instrumenting, running, and generating reports.
        </p>

        <p>
            The best way to do this is to specify the location
            of the data file when running your tests. You should pass the
            <code>-Dnet.sourceforge.cobertura.datafile=${basedir}/cobertura.ser</code>
            sysproperty to the JUnit task.
        </p>

        <p>
            Another common problem is that the cobertura.ser file is
            deleted, but the previously instrumented classes are not
            also deleted. Any time you delete your coverage data file
            you should also deleted all instrumented classes.
        </p>

    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Why is Cobertura causing me to have classpath conflicts with ASM?
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura uses ASM to modify your bytecode. There are a few other
            popular programs that use ASM; Groovy and Hibernate, to name two.
            You could have problems if Cobertura uses a different version of
            asm and you add both versions to your classpath.
        </p>

        <p>
            Cobertura only uses ASM when instrumenting. Cobertura <i>does not
            need ASM in your classpath when running tests</i>. If you're seeing
            classpath conflicts, just make sure the asm jar that comes with
            Cobertura is used only by Cobertura, and only when instrumenting.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Is it possible to graphically show my test coverage over time?
        </p>
    </div>

    <div class="answer">
        <p>
            Yes, using <a href="http://qalab.sourceforge.net/index.html">QALab</a>.
            From their website, QALab "allows developers, architects and project
            managers alike to be presented with a trend of the QA statistics of
            their project."
        </p>
    </div>
</div>


<h2>Using Cobertura with a Web Application</h2>


<div class="faq">
    <div class="question">
        <p>
            I have automated tests that use HttpUnit/HtmlUnit/Empirix/Rational
            Robot, can I use Cobertura?
        </p>
    </div>

    <div class="answer">
        <p>
            Yes! The process is a bit more involved, but the concept is the same.
            First instrument your compiled classes. Then create your war file.
            Then deploy the war file into your application server (Tomcat, JBoss,
            WebLogic, WebSphere, etc). Now run your tests.
        </p>

        <p>
            As your classes are accessed, they will create a "cobertura.ser" file
            on the disk. You may need to dig around a bit to find it. Cobertura
            puts this file in what it considers to be the current working
            directory. Typically this is the directory that the application
            server was started from (for example, <code>C:\Tomcat\bin</code>)
            Note: <b>This file is not written
            to the disk until the application server exits</b>. See below for
            how to work around this.
        </p>

        <p>
            Now that you know where the cobertura.ser file is, you should modify
            your deploy step so that it moves the original cobertura.ser to the
            appropriate directory in your application server, and then moves it
            back when finished testing. Then run cobertura-report.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            I'm using JBoss. When I stop the server, the coverage data file is
            not written. Or the coverage data file is 0 bytes. Or
            cobertura-report and cobertura-merge complain that the coverage data
            file is invalid (possibly throwing an EOFException).
        </p>
    </div>

    <div class="answer">
        <p>
            Cobertura only writes the coverage data file at shutdown. It does
            this by adding a shutdown hook with
            <code>Runtime.getRuntime().addShutdownHook()</code>.
            JBoss has its own shutdown hook that calls <code>System.halt()</code>
            when its finished. If the JBoss shutdown hook finishes before the
            Cobertura shutdown hook, then the call to <code>System.halt()</code>
            causes the JVM to halt and the cobertura.ser file will be
            incomplete.
        </p>

        <p>
            To fix this, set <code>-Djboss.shutdown.forceHalt=false</code>
            when starting JBoss.
        </p>
    </div>
</div>


<br/>


<div class="faq">
    <div class="question">
        <p>
            Cobertura only writes the coverage data file when the
            application server shuts down. We do not want to stop
            our application server after running our tests.
        </p>
    </div>

    <div class="answer">
        <p>
            It is possible to instruct Cobertura to write the data
            file. One of your classes should call the static method
            <code>net.sourceforge.cobertura.coveragedata.ProjectData.saveGlobalProjectData()</code>.
            For example, you could add something like this to a
            "logout" method in your web application:
        </p>

        <blockquote>
<pre>try {
    String className = "net.sourceforge.cobertura.coveragedata.ProjectData";
    String methodName = "saveGlobalProjectData";
    Class saveClass = Class.forName(className);
    java.lang.reflect.Method saveMethod = saveClass.getDeclaredMethod(methodName, new Class[0]);
    saveMethod.invoke(null,new Object[0]);
} catch (Throwable t) {
}</pre>
        </blockquote>

        <p>
            We are looking for a better alternative to this. Feel
            free to send us your suggestions. Possible changes in
            future versions of Cobertura:
        </p>

        <ul>

            <li>Add the ability to set a timer that saves the data
                file on a given interval. See
                <a href="https://sourceforge.net/tracker/index.php?func=detail&amp;aid=1255463&amp;group_id=130558&amp;atid=720017">patch
                    #1255463</a> for details.
            </li>

            <li>Add the ability for end-users to add a "magic"
                string literal to their code that Cobertura would
                remove during instrumentation and replace with a
                call to flush the coverage data to disk. This
                idea was proposed by Eugene Kuleshov in an
                <a href="https://sourceforge.net/mailarchive/message.php?msg_id=13889985">email
                    to the cobertura-devel mailing list</a>.
            </li>

            <li>After ASM 2.2 is released, possibly save the coverage
                data when exiting a method, as suggested by Eugene
                Kuleshov in an
                <a href="https://sourceforge.net/mailarchive/message.php?msg_id=13879807">email
                    to the cobertura-devel mailing list</a>.
            </li>

            <li>Provide web application developers with an easy way
                for them to ask Cobertura to flush the coverage data to
                disk.
            </li>

        </ul>
    </div>
</div>


</div>

<?php include("footer.html"); ?>
